<?php
/**
 * PureMVC Port to PHP originally translated by Asbjørn Sloth Tønnesen
 *
 * @author Omar Gonzalez :: omar@almerblank.com
 * @author Hasan Otuome :: hasan@almerblank.com
 *
 * Created on Sep 24, 2008
 * PureMVC - Copyright(c) 2006-2008 Futurescale, Inc., Some rights reserved.
 * Your reuse is governed by the Creative Commons Attribution 3.0 Unported License
 */

/**
 * The interface definition for a PureMVC Controller.
 *
 * <P>
 * In PureMVC, an <code>IController</code> implementor
 * follows the 'Command and Controller' strategy, and
 * assumes these responsibilities:
 * <UL>
 * <LI> Remembering which <code>PureMVC_Command_Interface</code>s
 * are intended to handle which <code>PureMVC_Observer_Notification_Interfaces</code>.</LI>
 * <LI> Registering itself as an <code>PureMVC_Observer_Interface</code> with
 * the <code>View</code> for each <code>PureMVC_Observer_Notification_Interface</code>
 * that it has an <code>PureMVC_Command_Interface</code> mapping for.</LI>
 * <LI> Creating a new instance of the proper <code>PureMVC_Command_Interface</code>
 * to handle a given <code>PureMVC_Observer_Notification_Interface</code> when notified by the <code>View</code>.</LI>
 * <LI> Calling the <code>PureMVC_Command_Interface</code>'s <code>execute</code>
 * method, passing in the <code>PureMVC_Observer_Notification_Interface</code>.</LI>
 * </UL>
 *
 * @see org.puremvc.php.interfaces PureMVC_Observer_Notification_Interface
 * @see org.puremvc.php.interfaces PureMVC_Command_Interface
 */
interface PureMVC_Controller_Interface
{

	/**
	 * Register a particular <code>PureMVC_Command_Interface</code> class as the handler
	 * for a particular <code>PureMVC_Observer_Notification_Interface</code>.
	 *
	 * @param notificationName the name of the <code>PureMVC_Observer_Notification_Interface</code>
	 * @param commandClassRef the Class of the <code>PureMVC_Command_Interface</code>
	 */
	public function registerCommand( $notificationName, $commandClassRef );

	/**
	 * Execute the <code>PureMVC_Command_Interface</code> previously registered as the
	 * handler for <code>PureMVC_Observer_Notification_Interface</code>s with the given notification name.
	 *
	 * @param notification the <code>PureMVC_Observer_Notification_Interface</code> to execute the associated <code>PureMVC_Command_Interface</code> for
	 */
	public function executeCommand( PureMVC_Observer_Notification_Interface $notification );

	/**
	 * Remove a previously registered <code>PureMVC_Command_Interface</code> to <code>PureMVC_Observer_Notification_Interface</code> mapping.
	 *
	 * @param notificationName the name of the <code>PureMVC_Observer_Notification_Interface</code> to remove the <code>PureMVC_Command_Interface</code> mapping for
	 */
	public function removeCommand( $notificationName );
}
